Projet:Afripédia/Documentation technique

Ce document décrit les différentes procédures techniques nécessaires à la mise en place et à l'animation de Kiwix dans le cadre du projet Afripédia. Cette documentation est thématique et non linéaire.

Contacts[modifier | modifier le code]

Liste de discussion des participants: afripedia@lists.wikimedia.fr
Développeurs de Kiwix: contact@kiwix.org ou Chat ou Rapporter un bug

Généralités[modifier | modifier le code]

Important: Copiez le contenu de la clef USB sur votre ordinateur (ou même plusieurs). La clef peut se perdre, se casser ou autre ; elle est remplaçable, mais le contenu est trop lourd pour être re-téléchargé facilement. Ayez une copie de sauvegarde du contenu.

«Router» désigne l'équipement fourni (Routeur Netgear N300) mais dans toutes les configurations proposées, il est utilisé (et configuré) comme un point d’accès WiFi.

Déploiements[modifier | modifier le code]

Plug seul[modifier | modifier le code]

Le plug peut fonctionner de manière autonome, avec la clef et une prise de courant ; c'est-à-dire sans équipement réseau supplémentaire (router). Cette utilisation est très pratique pour les démonstrations et les petites conférences/barcamp. Cette solution bien que valable n'est pas conseillée s'il existe un équipement réseau car:

La couverture WiFi du plug (réseau KIWIX_PLUG) est très faible.
Les performances sont légèrement moindre dû aux éventuelles congestions réseau.

À savoir:

Le plug met un peu moins de 3mn à démarrer. En attendant, le réseau KIWIX_PLUG n’existe pas.
Le plug est démarré et prêt à l’usage une fois la lumière bleu clignotante affichée.
Il n’y a pas de bouton marche/arrêt. Pour éteindre le plug, il suffit de le débrancher.
Si le plug démarre sans la clef, il ne fonctionnera pas correctement. Il faut alors le débrancher/rebrancher (reboot).
La connexion ssh vers le plug est coupée au démarrage lorsque la clef est présente. Pour faire des modifications sur le plug, démarrer sans la clef ou voir la section personnalisations.
Si la clef est enlevée du plug et remise, le plug ne fonctionnera pas correctement. Il faut le redémarrer.
Le plug et la clef chauffent. C’est un comportement normal. En cas de doute, débrancher, laisser refroidir puis rebrancher.
Pour diagnostiquer les problèmes:
- Vérifier les lumières du plug. Il doit y avoir un vert fixe d’un côté et un bleu clignotant de l’autre. Si non, reboot.
- Vérifier la page de statut: Adresse /@status sur le plug.
- Dans tous les cas, la seule action possible est le reboot.

Plug avec Router[modifier | modifier le code]

C'est la configuration standard, correspondant à la dotation matérielle. Cette configuration est recommandée pour donner accès au contenu sur une zone fixe et limitée (CNF, campus, amphi, etc).

Dans cette configuration, le plug est branché au router par un câble réseau RJ45 (port extérieur du plug et port LAN/Orange du routeur).

Le plug diffuse son réseau WiFi KIWIX_PLUG (cf. Plug seul) et le routeur diffuse également un réseau WiFi nommé KIWIX. Le réseau KIWIX a une portée et un débit plus large ; il est conseillé de rediriger les utilisateurs vers lui.

Le router est configuré en mode AP (Access Point) et ne diffuse pas de DHCP. Il route cependant le trafic entre le WiFi et le LAN. Son adresse IP est 192.168.2.2.

Il est possible de désactiver le réseau KIWIX_PLUG (cf. personnalisations).

Plug avec plusieurs équipements réseaux[modifier | modifier le code]

Cette configuration est une amélioration de la configuration standard: elle consiste à ajouter des équipements réseau pour étendre et/ou multiplier la couverture réseau.

Deux approches différentes existent ; elles ne sont pas exclusives et peuvent donc se combiner.

Plusieurs zones de couverture[modifier | modifier le code]

En ajoutant des point d’accès WiFi, il est possible de diffuser les contenus d'un plug à plusieurs endroits.

Pour ce faire, l'on connectera plusieurs AP WiFi ou router au port extérieur du plug:

En utilisant un switch et plusieurs AP connectés au switch.
En branchant les autres AP WiFi aux ports LAN du router.
En utilisant des adaptateurs CPL pour utiliser le réseau électrique comme réseau de données ; pratique pour relier plusieurs bâtiments (attention, ils doivent tous être sur le même réseau électrique).

Une zone étendue[modifier | modifier le code]

En ajoutant des répéteurs WiFi, il est possible d'étendre la couverture WiFi du routeur. Il faut alors configurer la connexion WiFi/WiFi sur les répéteurs (dépends des équipements).

Kiwix Desktop[modifier | modifier le code]

C'est la configuration historique de Kiwix.

Elle permet à quiconque qui possède le logiciel Kiwix et un contenu ZIM (par exemple Wikipédia en français) de le consulter directement sur son ordinateur ; sans connexion (Internet ou autre).

Cette configuration peut être utilisée par les étudiants lorsqu'ils ne sont pas à proximité d'un réseau Afripedia ou Internet.

Cette configuration peut aussi être utilisée sur n'importe quel ordinateur, connecté ou non. Par exemple, dans les cybercafés, c'est une alternative plus rapide d'accès à Wikipedia pour la consultation.

Utiliser Kiwix[modifier | modifier le code]

Kiwix est un projet autonome avec sa communauté et son propre site Web: kiwix.org.

Kiwix est un lecteur de contenus ZIM. Un contenu ZIM est un fichier compressé contenant un groupement de contenus. Majoritairement, les contenus ZIM sont des sites web qui sont proposés au format ZIM pour être consultés sans connexion Internet.

Le projet Kiwix met à disposition de nombreux contenus ZIM tels que :

Wikipedia en français
Wikipedia dans d'autres langues
Wikileaks
Documentation Ubuntu francophone

Il est prévu de créer des contenus ZIM pour le Wiktionnaire et Wikisource prochainement.

Installer Kiwix[modifier | modifier le code]

Kiwix est disponible pour plusieurs plateformes; l'installation se présente donc de manières différentes. Toutes ces versions sont téléchargeables sur le site web de Kiwix.

Sur le plug se trouve une version pour chacun des principaux systèmes:

kiwix.zip pour Windows (version XP et plus)
kiwix.dmg pour Mac OS X (version 10.6 et plus)
kiwix.tar.bz2 pour GNU/Linux (toutes distribution 2.6+)
kiwix-src.tar.gz, le code source de Kiwix

Conseil: Vous pouvez ajouter d'autres versions dans le dossier packages de la clé USB, notamment la version «installeur» de Kiwix pour Windows ; ou encore une version non-compressée de Kiwix pour linux (.tar au lieu de .tar.bz2).

Hormis la version «installeur» pour Windows et les versions «packagées» pour Linux, Kiwix se présente comme un fichier à décompresser. Une fois décompressé, le répertoire créé contient un binaire kiwix ou kiwix.exe qui permet de lancer le logiciel.

Lire un fichier ZIM[modifier | modifier le code]

Lire un fichier ZIM présent sur l'ordinateur est très simple et rapide: Une fois dans le logiciel Kiwix:

Choisir le menu Fichier
Choisir le sous-menu Ouvrir
Sélectionner le fichier ZIM via la boite de dialogue.

C'est fini, le fichier se charge et sa page d'accueil s'affiche. Kiwix proposera alors d'indexer le contenu du fichier ZIM pour activer la recherche plein-texte (cf. ci-dessous).

Indexer un fichier ZIM[modifier | modifier le code]

A l'ouverture d'un fichier ZIM (ou lors des tentatives de recherche si l'indexation n'a pas été déjà faite), Kiwix proposera d'indexer le fichier ZIM.

L'index est une liste croisée de tous les mots et tous les articles. C'est ce qui permet la recherche plein-texte (cf. ci-dessous).

L'indexation est un processus long, dont la durée est proportionnelle a la taille du fichier ZIM. Pour la Wikipédia en français, cela représente plusieurs heures sur un ordinateur très rapide.

Le processus ne peut pas être interrompu puis repris ; mais il peut être annulé puis relancé plus tard.

Indexer depuis Kiwix[modifier | modifier le code]

Depuis le logiciel, soit ouvrir le fichier ZIM concerné et répondre Oui à la demande d'indexation, soit, si le fichier ZIM est déjà ouvert, tenter une recherche plein-texte et répondre à la même question.

Une fois le processus lancé, une barre de progression s'affiche en bas à droite de la fenêtre. Il n'y a pas d'estimation de la durée.

Une fois l'indexation finie, un message s'affiche et la recherche plein-texte fonctionne.

Important:

Le fichier d'index se crée dans le répertoire profil de l'utilisateur
Le fichier d'index peut représenter de 10% à 20% de la taille du fichier ZIM. Pour la Wikipédia en français, l'index généré pèse 5Gio.
Il faut donc veiller à disposer de suffisamment d'espace sur le disque concerné
Il est possible de compresser l'index (2Gio pour WP) pour réduire sa taille. cf. ci-dessous.

Indexer avec kiwix-index[modifier | modifier le code]

Il est possible d'indexer un fichier ZIM hors de Kiwix, en ligne de commande. Le logiciel utilisé pour cela se nomme kiwix-index ou kiwix-index.exe et se trouve dans le dossier bin du dossier de Kiwix.

Utilisation:

./kiwix-index -v -b=xapian wikipedia_092012.zim wikipedia_0912.idx

Dans cet exemple, il faudra remplacer wikipedia_092012.zim par le chemin vers le fichier ZIM à indexer et wikipedia_0912.idx par le dossier de destination souhaitée pour l'index.

Réutiliser un Index existant[modifier | modifier le code]

cf. Fournir un ZIM avec son Index.

Faire des recherches[modifier | modifier le code]

Il existe deux types de recherches sur Kiwix:

La recherche sur les titres (aussi appelée suggestions)
La recherche plein-texte.

La recherche sur les titres est disponible dans la barre de recherche de Kiwix. Lors de la frappe, une liste de noms d'articles apparait. C'est la recherche sur les titres.

Comme son nom l'indique, elle ne s’opère que sur les noms des titres. Elle affichera donc uniquement les articles dont le nom commence par le texte saisi. Ainsi, en saisissant «Bamako», l'on se verra proposer les articles Bamako et Bamako (film) mais pas Monuments de Bamako ni Mali.

Il suffit de sélectionner l'article dans cette liste pour y être redirigé.

La recherche plein-texte, elle, s’opère sur l'ensemble du contenu des articles. On y accède par le même champ de recherche. Si le texte saisi ne donne pas lieu à des suggestions, il suffit de valider pour obtenir la liste des résultats. S'il existe des suggestions, il faut sélectionner «Contenant xxx…» dans la liste.

La page des résultats de recherche donne la liste des articles classés par nombre d’occurrences du texte cherché. Ainsi, une recherche sur «Mali» donnera en premier lieu les pages Catégorie:Wikipédia:ébauche ville du Mali et Liste des matchs de l'équipe du Mali de football par adversaire alors que l'article Mali se trouve plus loin dans la liste. C'est parce que ces pages contiennent plus d’occurrences du mot «Mali» que l'article Mali.

Fournir un ZIM avec son Index[modifier | modifier le code]

La manière la plus confortable pour installer, partager et utiliser Kiwix est d'obtenir à la fois le contenu et l'index. De cette manière, l'utilisateur aura accès à toutes les fonctionnalités sans avoir à créer l'index lui-même.

Pour ce faire, il faut:

Fournir le contenu et l'index dans une arborescence spécifique
Placer ce dossier à côte du dossier Kiwix sur l'ordinateur de l'utilisateur.

L'arborescence est la suivante:

data/
	content/
		_wikipedia_fr_all_09_2012.zim
	index/
		_wikipedia_fr_all_09_2012.zim.idx/
	library/
		library.xml

Au lieu du fichier _wikipedia_fr_all_09_2012.zim on peut avoir plusieurs fichiers _wikipedia_fr_all_09_2012.zimaa, _wikipedia_fr_all_09_2012.zimab, etc.

Une fois l'arborescence créée, on partage le dossier data avec l'utilisateur.

Il faut ensuite placer ce répertoire data sur l'ordinateur de l'utilisateur à côté du dossier Kiwix ; comme ceci:

kiwix/
	bin/
	xulrunner/
	components/
	defaults/
	chrome/
	kiwix.exe
	chrome.manifest
	application.ini
data/
	content/
	index/
	library/

Utiliser d'autres chemins/disques[modifier | modifier le code]

Il est possible d’utiliser d’autres emplacements pour le contenu et l’ index qui sont tous deux volumineux. Pour ce faire, il faut créer un dossier data contenant un dossier library contenant lui-même un fichier library.xml exactement comme à l’étape précédente, mais dans copier les dossiers content et index.

Une fois ceci fait, il faut changer le contenu du fichier library.xml pour indiquer les emplacements réels des fichiers contenus et index.

Exemple, le fichier original:

<book path="../content/_wikipedia_fr_all_07_2011.zim" indexPath="../index/_wikipedia_fr_all_07_2011.zim.idx" indexType="xapian" title="Wikipédia" … />

deviendrait :

<book path="D:/wikipedia/content/_wikipedia_fr_all_07_2011.zim" indexPath="D:/wikipedia/index/_wikipedia_fr_all_07_2011.zim.idx" indexType="xapian" title="Wikipédia" … />

Plus d’informations sur l’édition du fichier library.xml ci-dessous.

Utiliser la bibliothèque Kiwix[modifier | modifier le code]

Kiwix dispose d’une bibliothèque interne qui permet deux choses:

Lister et permuter les contenus ZIM installés sur l’ordinateur: Bibliothèque locale.
Lister et télécharger les contenus ZIM disponibles sur Internet: Bibliothèque distante.

On accède à ces deux bibliothèques par le bouton bibliothèque de la barre d’outils. Par défaut, celui-ci affiche la bibliothèque distante. Elle peut être vide si l’ordinateur n’était pas connecté à Internet lors du lancement de Kiwix.

Si elle n’est pas vide, elle liste tous les contenus disponibles en ligne avec des informations comme la taille, la langue, etc. Il est possible de télécharger (et de mettre en pause/reprendre) les contenus directement depuis Kiwix. Ils seront stockés dans le répertoire du profil Kiwix (~/www.kiwix.org pour Linux, ou ~/Library/Kiwix pour OSX ou Application Data du disque principal pour Windows) et apparaîtrons dans la bibliothèque locale.

On accède à la bibliothèque locale par le menu situé à gauche. La liste permet de changer le contenu ZIM actif.

Kiwix Desktop en mode serveur[modifier | modifier le code]

La version Desktop de Kiwix comporte une option qui transforme Kiwix en serveur de contenus ZIM (à la manière de kiwix-serve).

On utilisera cette configuration dans le cadre d’un réseau local (filaire ou sans-fil) où l’on ne dispose pas de matériel (serveur, plug) sur lequel installer kiwix-serve. Cette configuration est donc toute indiquée pour les salles informatiques ou bibliothèques sans ressources.

Pour ce faire, il faut:

Avoir installé et configuré Kiwix avec un contenu (et de préférence un index) tel que décrit ci-dessus.
Lancer le mode serveur depuis le menu Outils -> Serveur
1. Choisir un port (optionnel) et le retenir. Par défaut, le port 8000.
2. Démarrer le service.
3. S’assurer du bon fonctionnement en cliquant sur le lien.

Pour accéder aux contenus depuis les autres ordinateurs du réseau, il faut entrer l’adresse IP de l’ordinateur configuré dans le navigateur Web, suivi du port choisi lors du lancement du mode serveur.

Par exemple, http://192.168.1.8:8000 . L’utilisation est ensuite identique à la consultation de contenus à travers kiwix-serve.

Kiwix-serve[modifier | modifier le code]

Cette configuration s’applique à un intranet existant ; ou l’usage du plug n’est pas souhaité car le réseau, filaire ou sans-fil existe et fonctionne. L’on y ajoute simplement le kiwix-serve pour fournir les contenus ZIM aux usagers. Il est conseillé d’utiliser un serveur Web en plus (cf. config ci-dessous), mais kiwix-serve peut fonctionner seul, si nécessaire.

Il est à noter que dans ce cas, aucune statistique ou log n’est produit et que l’on ne peut pas télécharger les fichiers ZIM, seulement les consulter.

kiwix-serve est disponible dans le dossier bin de toute installation de Kiwix. C’est un binaire en ligne de commande. Il est aussi packagé pour Debian et d’autres distributions. Voir sur site de Kiwix.

Usage: kiwix-serve [--index=INDEX_PATH] [--port=PORT] [--verbose] [--daemon] [--attachToProcess=PID] ZIM_PATH
       kiwix-serve --library [--port=PORT] [--verbose] [--daemon] [--attachToProcess=PID] LIBRARY_PATH

kiwix-serve possède deux modes de fonctionnement:

Servir un seul fichier ZIM

Ce mode est le plus simple à lancer si l’on dispose d’un seul fichier ZIM et que l’on n'a pas de fichier library.xml. Il s’utilise comme ceci:

kiwix-serve --index=/home/user/data/index/_wikipedia092012.zim.idx --port=8000 /home/user/data/content/_wikipedia092012.zim

Servir un ou plusieurs fichiers ZIM (mode bibliothèque).

C’est le mode recommandé. Une fois le fichier library.xml prêt et identifié (il est disponible dans le dossier data/library de la clef), on le lance tel que:

kiwix-serve --library /home/user/data/library/library.xml --port 8000

Dans les deux cas, les options suivantes sont applicables:

--port=PORT: choisir le port sur lequel démarrer le serveur HTTP.
--verbose: Afficher les requêtes dans la console.
--daemon: Démarrer en mode démon (double fork).
--attachToProcess=PID: éteindre kiwix-serve à la fermeture du process indiqué.

kiwix-serve fonctionne à la manière d’un serveur Web classique et répond ensuite aux requêtes HTTP sur le port configuré. Par défaut (/), il affiche la liste des contenus ZIM disponibles dans la bibliothèque.

Fonctionnalités:

Liste des contenus (/)
Bandeau de recherche
Suggestions (/suggest) dans le bandeau de recherche
Recherche plein-texte (si index présent) (/search)

Kiwix-serve avec serveur Web[modifier | modifier le code]

Cette configuration est une variante améliorée de la configuration kiwix-serve. Elle consiste à ajouter un serveur Web qui jouera le rôle de proxy pour kiwix-serve. Les avantages sont:

Possibilité d’avoir des logs et donc des statistiques
Possibilité de télécharger des contenus, en plus de la consultation.
Possibilité de page d’accueil personnalisé.
Meilleures performances.

Pour mettre en place cette configuration, il faut suivre intégralement les instructions de la configuration kiwix-serve en gardant à l’esprit que le port ne sera pas utilisé par les utilisateurs finaux. On utilisera donc un port quelconque. Le plug par exemple utilise le port 4201 pour kiwix-serve.

La configuration est ensuite simple, il suffit de configurer un serveur Web avec:

Proxy HTTP vers l’IP et le port de kiwix-serve.
Activer les logs au format Apache.

Le plug utilise le serveur Web nginx car celui-ci est très léger, performant et sa configuration simple.

Il y a plusieurs URL à configurer (forwarder) pour obtenir toutes les fonctionnalités de kiwix-serve:

/ ou /_ est utilisé pour servir les contenus ZIM.

Par convention, sur le plug, on préfixe les ZIM par un _ pour ne pas avoir de collision d’URL.

/search: utilisé pour la recherche plein-texte.
/suggest: utilisé pour la recherche sur les titres (suggestions). Cette URL est appelée via JavaScript et non saisie.
/skin: utilisé pour servir les CSS et JS de Kiwix (page listant les contenus, barre de recherche).

Exemple de configuration du proxy:

server {
  error_page   404 = /;

  access_log /var/log/nginx/afripedia.access.log;

  location /_ {
          rewrite /_(.*)        /_$1 break;
          proxy_pass            http://localhost:4201;
          proxy_set_header      X-Real-IP  $remote_addr;
  }

  location /search {
          rewrite /search(.*)   /search$1 break;
          proxy_pass            http://localhost:4201;
          proxy_set_header      X-Real-IP  $remote_addr;
  }

  location /suggest {
          rewrite /suggest(.*)  /suggest$1 break;
          proxy_pass            http://localhost:4201;
          proxy_set_header      X-Real-IP  $remote_addr;
  }

  location /skin {
          rewrite /skin/(.*)    /skin/$1 break;
          proxy_pass            http://localhost:4201;
          proxy_set_header      X-Real-IP  $remote_addr;
  }

  location / {
          rewrite /(.*)         /$1 break;
          proxy_pass            http://localhost:4201;
          proxy_set_header      X-Real-IP  $remote_addr;
  }
}

Il est recommandé de s’inspirer/se baser sur la configuration nginx du plug, située dans le dossier conf/nginx.conf de la clef.

Personnalisations du Plug[modifier | modifier le code]

La majorité des modifications applicables au plug s’effectuent en modifiant la clef. Il est fortement conseillé de sauvegarder son contenu original afin de prévenir les mauvaises manipulations ou simplement restaurer le fonctionnement initial.

Formater la clef[modifier | modifier le code]

La clef a été formatée en format FAT32, afin d’être lisible sur des ordinateurs Windows (pour la récupération des statistiques par exemple). Si vous n’avez pas l’utilité de la compatibilité Windows, il est conseillé de reformater la clef en un meilleur format, par exemple ext4, ext3, ext2.

Ext4 est plus rapide, même si ce n’est pas très visible dans notre cas de figure.
Ext4 autorise les fichiers de plus de 4Gio, très pratique dans notre cas de figure.
Ne pas utiliser NTFS car la récupération en cas de démontage non propre (extinction du plug) peut poser des problèmes au montage de la clef.

Une fois la clef formatée, vous pouvez replacer les fichiers sauvegardés précédemment sur la clef.

Un des avantages d’ext étant le support des gros fichiers, il est conseillé de regrouper les fichiers zimaa, zimab, etc en un seul fichier. Cela sera plus pratique à télécharger par les utilisateurs du plug.

Pour ce faire, (sous Linux), se placer (dans un terminal), dans le dossier des fichiers zimaa et autres:

cat wikipedia_092012.zima* > wikipedia_092012.zim

En remplaçant wikipedia_092012.zima par la partie commune du nom des fichiers.

Modifier la page d'accueil[modifier | modifier le code]

La page accueil du plug et/ou du serveur Web (non applicable pour kiwix-serve ou le mode serveur) est une page HTML statique simple. Elle se trouve sur la clef à l’emplacement system/landing. Il est possible de la modifier entièrement à votre guise.

Les liens relatifs au plug sont les suivants:

/contents2download/: pointe vers le dossier data/content de la clef et en affiche un listing pour téléchargement.
/packages2download/: pointe vers le dossier packages de la clef et en affiche un listing pour téléchargement. C’est là que se trouvent les différentes versions de Kiwix.
/search: Les résultats de recherche.
/@status: la page de diagnostics du plug.
/@stats/: les statistiques HTML de consultation du plug.
/_xxxxx/: La page d’accueil du fichier ZIM _xxxxx. Par convention, tous les fichiers ZIM du plug doivent commencer par un “_”.
/downloads/: pointe vers le dossier goinfre de la clef et en affiche un listing pour téléchargement.

Ajouter un contenu ZIM[modifier | modifier le code]

Ajouter un nouveau contenu ZIM consiste à ajouter les fichiers sur la clef, puis à modifier la bibliothèque pour indiquer les nouveaux contenus au kiwix-serve.

Copier le fichier ZIM (ou les fichiers zimaa, zimab, etc) dans le dossier data/content de la clef.
Copier l’index du fichier ZIM (dossier .idx) dans le dossier data/index de la clef. Par convention, on le nomme comme le fichier ZIM suivit de .idx, mais ce n’est pas obligatoire.
Éditer le fichier library/library.xml de la clef pour ajouter le nouveau contenu (<book>) ou utiliser kiwix-manage.

Indexer un ZIM avec `kiwix-index`[modifier | modifier le code]

Il est possible d’indexer un fichier ZIM en ligne de commande, cf. kiwix-index.

Modifier un `library.xml` avec `kiwix-manage`[modifier | modifier le code]

Le fichier library.xml ou bibliothèque est le fichier utilisé par Kiwix pour connaitre la liste des contenus ZIM disponibles. Il est utilisé aussi bien par Kiwix Desktop que par kiwix-serve.

Dans le cas de kiwix-serve, le nom du fichier n’a pas d’importance puisque le fichier est un paramètre de la commande ; pour la version Desktop en revanche, on conservera son nom car Kiwix “cherche” ce fichier à divers emplacements :

Dans le répertoire profil de Kiwix.
Dans le répertoire ../data/library/.

Le fichier library.xml peut être créé à partir de rien, à partir d’un autre, il peut être modifié directement (c’est un fichier texte) ou via le logiciel kiwix-manage.

kiwix-manage se trouve dans le répertoire bin du dossier d’installation de Kiwix. C’est un binaire en ligne de commande.

Usage:
	kiwix-manage LIBRARY_PATH add ZIM_PATH [--zimPathToSave=../content/foobar.zim] [--current|-c] [--indexBackend|-b=xapian|clucene] [--indexPath|-i=FULLTEXT_IDX_PATH] [url|u=http://...metalink]
	kiwix-manage LIBRARY_PATH show [CONTENTID1] [CONTENTID2] ... (show everything if no param.)
	kiwix-manage LIBRARY_PATH remove CONTENTID1 [CONTENTID2]

kiwix-manage peut être invoqué selon trois modes: afficher le contenu d’une bibliothèque, y ajouter un contenu ZIM ou en retirer un contenu ZIM. Dans tous les cas, la commande commence telle que: ./kiwix-manage /home/user/data/library/library.xml où /home/user/data/library/library.xml est le chemin vers le fichier library.xml. Si le fichier n’existe pas, il sera créé (dans le cas d’un ajout). Le dossier de destination doit exister cependant.

Les trois modes correspondent au mot clef d’action dans la commande :

Ajouter un contenu ZIM: ./kiwix-manage /home/user/data/library/library.xml add /home/user/data/content/_wikipedia_092012.zim --indexPath=/home/user/data/index/_wikipedia_092012.zim.idx --indexBackend=xapian --zimPathToSave=../content/_wikipedia_092012.zim
- /home/user/data/content/_wikipedia_092012.zim est le chemin vers le fichier ZIM concerné. Si ce sont plusieurs fichiers, on indique le chemin vers le fichier ZIM inexistant.
- /home/user/data/index/_wikipedia_092012.zim.idx est le chemin vers le dossier de l’index du ZIM.
- --zimPathToSave= permet de changer le chemin vers le ZIM dans le fichier library.xml. Cela rends le fichier library.xml plus portable si l’on y renseigne des chemins relatifs.
Afficher les contenus de la bibliothèque: ./kiwix-manage /home/user/data/library/library.xml show
- Affiche tous les contenus avec leur méta-données
- Indique l’identifiant interne de chaque contenu, nécessaire pour la suppression.
Supprimer un contenu ZIM de la bibliothèque: Ne pas utiliser pour le moment ; semble buggé. Les fichiers ZIM ne sont jamais supprimés. Cet outil modifie uniquement le fichier library.xml.

Ajouter d'autres contenus[modifier | modifier le code]

Il est possible d’ajouter d’autres contenus (non-ZIM) pour consultation/téléchargement. Pour ce faire, il suffit de les placer dans le dossier goinfre de la clef.

Les fichiers seront visibles à l’adresse /downloads/ du plug. Il est possible d’y mettre des fichiers HTML et des dossiers. Un dossier comportant un fichier index.htm ou index.html affichera celui-ci au lieu du listing de ses fichiers.

Consulter les statistiques[modifier | modifier le code]

Les statistiques de consultations utilisent le logiciel AWStats.

Elles sont consultables à l’adresse /@stats/ du plug.

Elles sont générées toutes les 60mn (à partir de la première heure), en fonction des logs du serveur Web. Ces statistiques sont pour votre usage et ne sont pas à transmettre à Afripédia.

Récupération des statistiques[modifier | modifier le code]

Les statistiques de consultation sont créés à partir des fichier de log du serveur Web.

Les statistiques sont générées dans le répertoire stats de la clef. Il n’est pas nécessaire de transmettre ce dossier à Afripédia.

Les logs du serveur Web, eux, sont écrits dans le répertoire log de la clef et sont à transmettre suivant le calendrier défini.

Pour transmettre les logs:

Retirer la clef du plug et la placer dans votre ordinateur.
Accéder à son contenu, et copier le dossier log.
Compresser le dossier log en ZIP, tar, tar/bzip/gzip
Envoyer l’archive compressée sur la liste de discussion Afripédia.
Replacer la clef dans le plug et le redémarrer.

Les logs sont anonymes et permettront d’en savoir plus sur les besoins en information des utilisateurs.

Modifier la configuration du Plug[modifier | modifier le code]

Le plug est configuré de manière à ce que le plus de configurations possibles soient sur la clef (pour pouvoir facilement modifier/mettre à jour).

La configuration du plug est donc inscrite dans le fichier system/kiwix-plug de la clef. C’est un fichier bash.

Pour information, le plug fonctionne sous GNU/Linux, avec Debian. Le processeur est un ARM.

Activer ssh[modifier | modifier le code]

Le serveur ssh est désactivé au lancement du script system/kiwix-plug (sur la clef) car il n’est pas nécessaire au fonctionnement du plug et le mot de passe du compte root est le mot de passe par défaut du Secure Shellplug}} : nosoup4u.

ssh est lancé cependant lorsque le plug démarre sans la clef. Vous pouvez activer ssh avec la clef en commentant la ligne if [ -e /etc/init.d/ssh ] ; then /etc/init.d/ssh stop ; fi. Ne pas faire sans modifier le mot de passe root. (Commenter veut dire que l'on mette # au début de la ligne.)

Le plug possède deux IP :

Une IP fixe, 192.168.2.2 sur le sur le port RJ45 extérieur (près de bord). (Cette adresse peut différer pour votre installation, mieux vérifier le script system/kiwix-plug.)
Une IP dynamique (le plug demande une IP via DHCP sur le réseau) sur le port RJ45 intérieur.

Renommer/désactiver le réseau WiFi du plug[modifier | modifier le code]

Le réseau interne du plug (KIWIX_PLUG) est pratique pour les démonstrations et les tests mais est inutile et génère de la confusion lorsqu’utilisé avec le routeur. Il est possible de changer son nom ou même de le désactiver complètement.

Pour changer son nom, modifier la ligne SSID=KIWIX_PLUG
Pour le désactiver, commenter la ligne uaputl bss_start dans system/kiwix-plug.

Corrections / Modifications[modifier | modifier le code]

Compatibilité Internet Explorer[modifier | modifier le code]

note : 16 novembre 2012, concerne uniquement les participants d’Abidjan

Grâce au C.N.F Bamako, nous avons découvert un bug important dans Kiwix : les utilisateurs d'Internet Explorer ne peuvent pas accéder aux contenus. Ils peuvent accéder à la page d’accueil du Plug, mais lorsqu’ils vont sur l’encyclopédie, le navigateur indique qu’il n’a pas pu se connecter au serveur. Cela fonctionne cependant avec les autres navigateurs sous Windows.

Il vous faut donc mettre à jour vos clefs. Pour ce faire, merci de suivre ces instructions:

Mise à jour du plug[modifier | modifier le code]

Télécharger le fichier kiwix-server-0.9-rc2-linux-armv5tejl.tar.bz2
Décompresser le fichier
Copier le fichier kiwix-serve du résultat vers le dossier system/bin/ de la clef USB.

Mise à jour des versions de Kiwix à télécharger[modifier | modifier le code]

Cette partie est moins importante, mais afin que vos utilisateurs (ou vous-même) ne soyez pas confrontés au même problème lors de l'utilisation de Kiwix en mode serveur, il vous faut utiliser la dernière version de Kiwix. De plus, cette nouvelle version de Kiwix apporte quelques corrections et modifications. Par exemple, le mode-serveur n’était pas disponible dans la version Windows présente sur la clef.

Télécharger les différentes versions de Kiwix depuis http://download.kiwix.org/bin/0.9_rc2/ : Windows (Installeur), Windows, Mac OSX, Linux, Linux (64 bits)
Renommer ces fichiers pour leur donner des noms plus explicites (ex. : kiwix-rc2-windows.exe)
Copier les fichiers dans le dossier packages/ de la clef USB.

Modèles de plugs supportés[modifier | modifier le code]

Les modèles de plugs suivants ont été testés et utilisés dans le cadre du projet Afripédia

DreamPlug : Modèle importé des États-Unis, a été utilisé lors du premier envoi de plugs en 2012.
TonidoPlug² : Modèle importé du Royaume-Uni, un peu moins onéreux, et normalement l'import vers la France est sans taxe.

Les modèles suivants ont été testés :

Raspberry Pi, modèle B : solution économique mais sans Wifi.